\vssub
\subsection{~Auxiliary programs} \label{sec:auxprog}

\vsssub
\subsubsection{General concepts}
\vsssub

All auxiliary programs presented here, with the exception of the track output
post-processor, read input from a pre-defined input file. Contents of that file
determine user choices for each auxiliary program. Comment lines are allowed
using a character determined by the user as follows: the first character
on the first line of the input file will be considered to be the comment
character, identifying comment lines throughout the input file. This comment character
has to appear on the first position of input lines to be effective. In all
examples in the following sections, the first character of the first line
is '{\tt \$}'. Therefore, all lines starting with '{\tt \$}' contain only
comments that are not parsed into the auxiliary program. As a standard,
auxiliary programs all write formatted output to the standard output unit.

In the following sections, all available auxiliary programs are described
using an example input file. These are found in the directory {\code inp} within the
\ws\ package. Inside each sample input file, all possible options that can be activated
by the user are included, most of them feature as comment lines starting with '{\tt \$}'.
Files in the current section reflect actual contents of sample files.
The sections below also show the name of the executable program associated with the 
displayed input file, the program name (as appears in the program statement), 
the source code file and input and output files and their unit numbers (in brackets 
behind the file name). Input and output files marked with \opt are optional. The 
intermediate files mentioned below are all {\F unformatted}, and are not described 
in detail here. Each file is written and read by a single routine, to which
reference is made for additional documentation.

\begin{list}{}{\itemsep 0mm \parsep 0mm \leftmargin 40mm \labelwidth 30mm}
\item[{mod\_def.ww3} \hfill] Subroutine {\F w3iogr} ({\file w3iogrmd.ftn}).
\item[{out\_grd.ww3} \hfill] Subroutine {\F w3iogo} ({\file w3iogomd.ftn}).
\item[{out\_pnt.ww3} \hfill] Subroutine {\F w3iopo} ({\file w3iopomd.ftn}).
\item[{track\_o.ww3} \hfill] Subroutine {\F w3iotr} ({\file w3iotrmd.ftn}).
\item[{restart.ww3}  \hfill] Subroutine {\F w3iors} ({\file w3iorsmd.ftn}).
\item[{nest.ww3}     \hfill] Subroutine {\F w3iobc} ({\file w3iobcmd.ftn}).
\item[{partition.ww3}\hfill] Subroutine {\F w3iosf} ({\file w3iosfmd.ftn}).
\end{list}

\noindent
Preprocessing and compilation of the programs is discussed in the following
two chapters. Examples of test runs of the model are provided with the source
code.

\vsssub
\subsubsection{Configuration file}
\vsssub

All auxiliary programs presented here read parameters and configuration from
either a namelist file (new form) or an input file (legacy form). Although most
auxiliary programs provide the option of a namelist file, some are still limited 
to using the legacy input file form. Namelist files for the latter programs
will become available in future public releases. For programs which already use 
namelists, template files are stored in model/nml directory. It is also possible
to convert the traditional {\file inp} file to new {\file nml} format using 
{\code bash} tools stored in the model/aux/bash directory. If {\file inp} 
and {\file nml} files are both present in
the run directory, the priority will be given to the namelist file. For
regtests, the default behavior is to run all the programs with {\file inp} file, the
option -N must be added to rather use {\file nml} file. Some new features are only 
available with namelists and the future developments will mainly be designed
for namelist use.

The namelist configuration file dedicated to a program provides a more 
readable and adaptative file. A {\file nml} file contains one or more namelists with
default values for each parameter with the possibility to overwrite them by a
user-defined value. There is no mandatory order to defined namelists in the
nml file. A namelist starts by '{\tt \&SOMETHING\_NML}' and stops by '{\tt /}'.
If a section is skipped from the namelist file, all the default values will be
used. When a program read its namelist file, all the default and user-defined
values for all namelists will be outputted in a log file for more tracability.

The traditional way to read the program configuration is from a pre-defined
input file. The first character on the first line of the input file will be
considered to be the comment character, identifying comment lines in the input
file. This comment character has to appear on the first position of input
lines to be effective. In all examples in the following sections lines starting
with '{\tt \$}' therefore only contain comment. The programs furthermore all
write formatted output to the standard output unit.

\vspace{\baselineskip} \noindent
Below is the part of an {\file inp} file with the corresponding part of {\file nml} file:

\vspace{\baselineskip} \noindent
\rule[1mm]{43mm}{.5mm} {\rm start of example input file (traditional form)}
\rule[1mm]{43mm}{.5mm}
\begin{footnotesize}
\begin{verbatim}
$ -------------------------------------------------------------------- $
$ WAVEWATCH III Grid preprocessor input file                           $
$ -------------------------------------------------------------------- $
$ Grid name (C*30, in quotes)
$
  'TEST GRID (GULF OF NOWHERE)   '
$
$ Frequency increment factor and first frequency (Hz) ---------------- $
$ number of frequencies (wavenumbers) and directions, relative offset
$ of first direction in terms of the directional increment [-0.5,0.5].
$ In versions 1.18 and 2.22 of the model this value was by definiton 0,
$ it is added to mitigate the GSE for a first order scheme. Note that
$ this factor is IGNORED in the print plots in ww3_outp.
$
   1.1  0.04118  32  24  0.
$
\end{verbatim}
\end{footnotesize}
\rule[1mm]{46mm}{.5mm} end of example input file (traditional form) 
\rule[1mm]{45.1mm}{.5mm}

\vspace{\baselineskip} \noindent
\rule[1mm]{43mm}{.5mm} {\rm start of example input file (namelist form)}
\rule[1mm]{43mm}{.5mm}
\begin{footnotesize}
\begin{verbatim}
! -------------------------------------------------------------------- !
! WAVEWATCH III - ww3_grid.nml - Grid pre-processing                   !
! -------------------------------------------------------------------- !


! -------------------------------------------------------------------- !
! Define the spectrum parameterization via SPECTRUM_NML namelist
!
! * namelist must be terminated with /
! * definitions & defaults:
!     SPECTRUM%XFR   = 0.  ! frequency increment
!     SPECTRUM%FREQ1 = 0.  ! first frequency (Hz)
!     SPECTRUM%NK    = 0   ! number of frequencies (wavenumbers)
!     SPECTRUM%NTH   = 0   ! number of direction bins
!     SPECTRUM%THOFF = 0.  ! relative offset of first direction [-0.5,0.5]
! -------------------------------------------------------------------- !
&SPECTRUM_NML
  SPECTRUM%XFR           =  1.1
  SPECTRUM%FREQ1         =  0.04118
  SPECTRUM%NK            =  32
  SPECTRUM%NTH           =  24
/
\end{verbatim}
\end{footnotesize}
\rule[1mm]{46mm}{.5mm} end of example input file (namelist form) 
\rule[1mm]{45.1mm}{.5mm}



\pb
